ATSUMeasureText

OSStatus ATSUMeasureText (
                     ATSUTextLayout iTextLayout,
                     UniCharArrayOffset iLineStart,
                     UniCharCount iLineLength,
                     ATSUTextMeasurement *oTextBefore,
                     ATSUTextMeasurement *oTextAfter,
                     ATSUTextMeasurement *oAscent,
                     ATSUTextMeasurement *oDescent);

iTextLayout

A reference of type ATSUTextLayout. Pass a reference to an initialized text layout object. You cannot pass NULL for this parameter.

iLineStart

A value of type UniCharArrayOffset. Pass the edge offset that corresponds to the beginning of the range of text whose typographic bounding rectangle you want to obtain. To indicate the beginning of the text buffer, pass the constant kATSUFromTextBeginning, described in Text Offset Constant. To indicate the entire text buffer, pass kATSUFromTextBeginning in this parameter and the constant kATSUToTextEnd in the iLineLength parameter. If the offset is outside the text buffer, ATSUMeasureText returns the result code kATSUInvalidTextRangeErr.

iLineLength

A value of type UniCharCount. Pass the length of the range of text whose typographic bounding rectangle you want to obtain. To indicate the end of the text buffer, pass the constant kATSUToTextEnd, described in Text Length Constant. To indicate the entire text buffer, pass kATSUToTextEnd in this parameter and the constant kATSUFromTextBeginning in the iLineStart parameter. If the range of text is outside the text buffer, ATSUMeasureText returns the result code kATSUInvalidTextRangeErr.

oTextBefore

A pointer to a value of type ATSUTextMeasurement. On return, the startpoint of the typographic bounding rectangle relative to the origin of the line in the current graphics port, taking into account cross-stream shifting. Assuming horizontal text, this corresponds to the left side of the bounding rectangle.

oTextAfter

A pointer to a value of type ATSUTextMeasurement. On return, the endpoint of the typographic bounding rectangle relative to the origin of the line in the current graphics port, taking into account cross-stream shifting. Assuming horizontal text, this corresponds to the right side of the bounding rectangle.

oAscent

A pointer to a value of type ATSUTextMeasurement. On return, the ascent of the typographic bounding rectangle relative to the origin of the line in the current graphics port, taking into account cross-stream shifting. Assuming horizontal text, this corresponds to the top side of the bounding rectangle.

oDescent

A pointer to a value of type ATSUTextMeasurement. On return, the descent of the typographic bounding rectangle relative to the origin of the line in the current graphics port, taking into account cross-stream shifting. Assuming horizontal text, this corresponds to the bottom side of the bounding rectangle.

function result

A result code. The result code kATSUInvalidCacheErr indicates that an attempt was made to read in style data from an invalid cache (that is, the format of the cached data does not match that used by ATSUI or the cached data is corrupt). The result code kATSUQuickDrawTextErr indicates that the QuickDraw function DrawText encountered an error while measuring a line of text. For a list of other ATSUI-specific result codes, see Result Codes.

DISCUSSION

The ATSUMeasureText function obtains the typographic bounding rectangle of a line of text, ignoring any previously set line attributes like rotation, flushness, justification, ascent, and descent. ATSUMeasureText obtains a single rectangle representing the typographic bounds. The coordinates of the rectangle are independent of the rendering device used to display the text.

To obtain the typographic bounds of a line after it is laid out, call the function ATSUGetGlyphBounds. To calculate the standard bounding rectangle of a laid-out line, call the function ATSUMeasureTextImage.

Before calculating the typographic bounding rectangle enclosing a range of text, ATSUMeasureText examines the text layout object to make sure that the style runs cover the entire range of text. If there are gaps between style runs, ATSUMeasureText assigns the characters in the gap to the style run following the gap. If there is no style run at the beginning of the range of text, ATSUMeasureText assigns these characters to the first style run it can find. If there no style run at the end of the range of text, ATSUMeasureText assigns the remaining characters to the last style run it can find.

ATSUMeasureText will not change or invalidate existing laid-out lines. Its main purpose is to give you feedback on the typographical extrema of a range of characters so you can position lines determine line breaks.

If the range of text is less than a line, ATSUMeasureText treats it as a line and ignores any previously set text layout attributes. If the range of text is exactly a line in length, ATSUMeasureText performs post-compensation actions on it. If the range of text extends beyond a line, ATSUMeasureText ignores soft line breaks (that is, it treats the text as a line).

You should call ATSUMeasureText to determine line breaks and other text fitting inquiry like the leading line spacing to impose on a line. It can also be used to determine where the line origin should go. This is important for editing and word processing applications, since it enables them to ascertain where to place the origin of the lines and leading spaces between lines.

Figure 2-1 illustrates the difference between the typographic bounding rectangle passed back by ATSUMeasureText and the standard bounding rectangle passed back by ATSUMeasureTextImage. The standard typographic bounding rectangle is the smallest rectangle that encloses the full span of the glyphs from the ascent line to the descent line, regardless of whether any glyphs extend to those lines. The width of the rectangle extends from the origin of the first glyph through the advance width of the last glyph, including any hanging punctuation and accounting for shifts due to optical alignment.

Figure 2-1 Standard and typographic bounding rectangle

SPECIAL CONSIDERATIONS

ATSUMeasureText may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

VERSION NOTES

Available beginning with ATSUI 1.0.